package org.zeapp.opencloud.framework.cloud;

import java.io.InputStream;
import java.io.OutputStream;
import java.util.List;

/**
 * This interface must be implemented by a Cloud service. This service are used
 * to perform all operation for saving file chunks in the cloud.
 * 
 * @author Amphiprion
 * 
 */
public interface Cloud {

	/**
	 * Return the file and directory entry directly under the given remote path.
	 * 
	 * @param remotePath
	 *            the remote path. Use "/" for root path.
	 * @return the list of remote entries
	 * @throws CloudException
	 *             if an error occurs
	 */
	List<CloudEntry> browseDirectory(String remotePath) throws CloudException;

	/**
	 * Retrieve the given remote file and store it in the given output stream.
	 * 
	 * @param remotePath
	 *            the remote path of the file
	 * @param outputStream
	 *            the output stream to write in
	 * @return the CloudFile representing the file
	 * @throws CloudException
	 *             if an error occurs
	 */
	CloudFile getFile(String remotePath, OutputStream outputStream)
			throws CloudException;

	/**
	 * Upload a file to the cloud.
	 * 
	 * @param remotePath
	 *            the full path where the file will be stored
	 * @param fileSize
	 *            the size of the file
	 * @param inputStream
	 *            the input stream
	 * @return the CloudFile representing the file
	 * @throws CloudException
	 *             if an error occurs
	 */
	CloudFile uploadFile(String remotePath, long fileSize,
			InputStream inputStream) throws CloudException;

	/**
	 * Create a new folder on the remote repository.
	 * 
	 * @param remotePath
	 *            the folder full path
	 * @return the CloudFolder representing the folder or null if the folder
	 *         already exists.
	 * @throws CloudException
	 *             if an error occurs
	 */
	CloudFolder createFolder(String remotePath) throws CloudException;
}
